Skip to main content

Messaging ExecModules

The ValkyrAI Workflow Engine provides comprehensive messaging capabilities through specialized ExecModules. These modules enable automated communication across multiple channels including SMS, email, and team collaboration platforms with enterprise-grade security and compliance.

Available Messaging Modules​

Twilio SMS/WhatsApp (msg.twilio.send)​

Send SMS and WhatsApp messages via the Twilio API with template support and media attachments.

Configuration Schema:

{
  "channel": "SMS|WHATSAPP",
  "to": "+14155551234",
  "from": "+14155559876",
  "body": "Your message content (max 2000 chars)",
  "media_urls": ["https://example.com/image.jpg"],
  "whatsapp_template": "template_name",
  "template_vars": {
    "customer_name": "John",
    "order_id": "12345"
  }
}

Integration Account Requirements:

  • apiKey: Twilio Account SID
  • password: Twilio Auth Token

WorkflowState Keys Emitted:

  • twilio.message.sid: Twilio message identifier
  • twilio.message.status: Message delivery status

Slack Channel Posting (msg.slack.post)​

Post messages to Slack channels with Block Kit support for rich formatting.

Configuration Schema:

{
  "channel": "#general",
  "text": "Fallback text for notifications",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Hello from ValkyrAI! :wave:"
      }
    }
  ],
  "thread_ts": "1234567890.123456"
}

Integration Account Requirements:

  • apiKey: Slack Bot Token (xoxb-...)
  • password: (Optional) Slack App Verification Token

WorkflowState Keys Emitted:

  • slack.ts: Message timestamp identifier
  • slack.channel: Channel where message was posted

Discord Channel Messaging (msg.discord.post)​

Send messages to Discord channels with embed support and file attachments.

Configuration Schema:

{
  "channel_id": "1234567890123456789",
  "content": "Your Discord message (max 2000 chars)",
  "embeds": [
    {
      "title": "Alert Title",
      "description": "Alert description",
      "color": 16711680,
      "fields": [
        {
          "name": "Field Name",
          "value": "Field Value",
          "inline": true
        }
      ]
    }
  ],
  "attachments": ["https://example.com/file.pdf"]
}

Integration Account Requirements:

  • apiKey: Discord Bot Token
  • password: (Optional) Additional verification

WorkflowState Keys Emitted:

  • discord.message.id: Discord message ID

Microsoft Teams Messaging (msg.teams.post)​

Post messages to Microsoft Teams channels via the Graph API with HTML formatting support.

Configuration Schema:

{
  "tenant_id": "12345678-1234-1234-1234-123456789012",
  "team_id": "team_id_here",
  "channel_id": "19:channel_id_here@thread.tacv2",
  "text": "Plain text message content",
  "html": "<h1>Rich HTML Content</h1><p>With formatting</p>"
}

Integration Account Requirements:

  • apiKey: Azure AD Application Client ID
  • password: Azure AD Application Client Secret

WorkflowState Keys Emitted:

  • teams.message.id: Microsoft Teams message ID

SendGrid Email (msg.sendgrid.email)​

Send transactional emails via SendGrid with template support and attachments.

Configuration Schema:

{
  "to": ["recipient@example.com", "admin@company.com"],
  "from": "noreply@company.com",
  "template_id": "d-1234567890abcdef",
  "dynamic_data": {
    "customer_name": "John Doe",
    "order_total": "$99.99"
  },
  "subject": "Your Order Confirmation",
  "plain_text": "Thank you for your order!",
  "html": "<h1>Thank you for your order!</h1>",
  "attachments": [
    {
      "filename": "receipt.pdf",
      "content_base64": "JVBERi0xLjQK..."
    }
  ]
}

Integration Account Requirements:

  • apiKey: SendGrid API Key
  • password: (Optional) Additional verification

WorkflowState Keys Emitted:

  • sendgrid.message.id: SendGrid message ID

Security & Compliance Features​

Data Protection​

  • PII Redaction: Email addresses and phone numbers are masked in logs
  • GDPR Compliance: Personal data handling follows GDPR requirements
  • Credential Security: API keys and tokens are securely stored and never logged

RBAC (Role-Based Access Control)​

All messaging modules enforce strict access controls:

  • USER: Can send messages with content approval workflows
  • ADMIN: Can send messages without restrictions
  • ANONYMOUS: Blocked from all messaging operations

Privacy Controls​

  • Phone Number Masking: Phone numbers logged as +1415***1234
  • Email Masking: Email addresses logged as user***@domain.com
  • Content Filtering: Sensitive content automatically redacted

Advanced Features​

Template Management​

Support for dynamic templates across platforms:

  • WhatsApp Business Templates: Pre-approved message templates
  • SendGrid Dynamic Templates: Personalized email campaigns
  • Slack Block Kit: Rich interactive message formatting

Delivery Tracking​

Comprehensive delivery status monitoring:

  • Real-time Status: Track message delivery in real-time
  • Failure Analysis: Detailed error reporting for failed messages
  • Retry Logic: Automatic retry with exponential backoff

Batch Operations​

Efficient bulk messaging capabilities:

  • Recipient Lists: Send to multiple recipients efficiently
  • Rate Limiting: Respect API rate limits automatically
  • Progress Tracking: Monitor bulk operation progress

Usage Examples​

Emergency Alert System​

// Send critical alerts across multiple channels
Workflow emergencyAlert = new Workflow()
    .addModule(new ExecModule()
        .moduleType("msg.slack.post")
        .moduleData("""
            {
              "channel": "#alerts",
              "text": "🚨 CRITICAL: System outage detected"
            }
            """))
    .addModule(new ExecModule()
        .moduleType("msg.teams.post")
        .moduleData("""
            {
              "team_id": "emergency-team",
              "channel_id": "general",
              "text": "System outage - all hands on deck"
            }
            """))
    .addModule(new ExecModule()
        .moduleType("msg.twilio.send")
        .moduleData("""
            {
              "channel": "SMS",
              "to": "+14155551234",
              "body": "CRITICAL: System outage. Check Slack for details."
            }
            """));

Customer Onboarding Sequence​

// Multi-channel customer onboarding
ExecModule welcomeEmail = new ExecModule()
    .moduleType("msg.sendgrid.email")
    .moduleData("""
        {
          "to": ["{{customer.email}}"],
          "template_id": "d-welcome-template",
          "dynamic_data": {
            "customer_name": "{{customer.name}}",
            "activation_link": "{{activation.url}}"
          }
        }
        """);

Team Collaboration Workflow​

// Cross-platform team notifications
Workflow teamNotification = new Workflow()
    .addModule(slackNotification)
    .addModule(teamsNotification)
    .addModule(discordNotification);

Error Handling & Monitoring​

Delivery Status Codes​

Each platform provides specific delivery status information:

SMS/WhatsApp (Twilio):

  • delivered: Message successfully delivered
  • failed: Permanent delivery failure
  • undelivered: Temporary delivery failure

Slack:

  • ok: true: Message posted successfully
  • error: Specific error code (channel_not_found, not_in_channel, etc.)

Email (SendGrid):

  • 202: Message accepted for delivery
  • 400: Request error (invalid recipient, etc.)
  • 401: Authentication error

Monitoring Dashboard Integration​

Export messaging metrics for monitoring:

// Extract delivery metrics
List<String> deliveryStatus = workflow.getWorkflowState()
    .stream()
    .filter(state -> state.getKey().endsWith(".status"))
    .map(WorkflowState::getValue)
    .collect(Collectors.toList());

Best Practices​

Message Content​

  1. Character Limits: Respect platform-specific limits
  2. Formatting: Use platform-native formatting (Markdown, HTML)
  3. Accessibility: Include alt text for media content
  4. Localization: Support multiple languages and time zones

Delivery Optimization​

  1. Timing: Send messages during recipient's active hours
  2. Frequency: Implement message frequency caps
  3. Segmentation: Target messages based on recipient preferences
  4. A/B Testing: Test message content and timing

Compliance​

  1. Opt-in/Opt-out: Respect subscription preferences
  2. Rate Limiting: Stay within API quotas
  3. Data Retention: Follow data retention policies
  4. Audit Trails: Maintain comprehensive logging for compliance